Add text boxes that include one or more "placeholders," each of which is replaced in the built document either with a value selected from a slicer or a value that is built dynamically by applying PQL functions to that slice. For example, you can add the name of the country from a slicer to a title or use PQL to make that name italic or to return some information from the internet about the selected country.
Placeholders typically update text to make sense of the analytic information that your visuals represent.
Placeholders are a type of dynamic text used to replace variables with slicer driven values or values derived from them. If you want to add variables to your text boxes that are replaced with data from your model, you need to add Dynamic Text fields instead.
- Click here for information about Dynamic Text
Configuring dynamic placeholders
You can add placeholders to text boxes that will be replaced when the publication is built either with values from your slicer or with values that are derived from those selections. You can use PQL Dynamic or Common expressions to build the custom functionality that transforms selected slicer values into other values or formats it by applying markup.
Step 1: Add a Text Box
Add a basic text box to your canvas, creating the basic text field that will include or be replaced by your placeholder or placeholders.
From the Toolbox:
- Click Text.
- Do one of the following:
- Click the canvas at the point where you would like to add your text field.
- Click and drag your cursor to draw a text field on your canvas. (This option allows you to customize the size of your text field.)
- Type or paste your required text into the text box.
A text box is added to the page at the selected point. Note: You will be able to move it at any time, so don't worry about this being the final location.
Your text field is created. You should re-size, format, or move your text as per your requirements. Once you are ready, remember to save your publication.
Step 2: Add placeholders to your text
These placeholders are the variables that you want to replace with the values from slicer elements when the document is built.
To add placeholders:
- Click inside the text box to place your cursor where you'd like to add the variable.
- Click Dynamic Text > Place Holder from the Component ribbon.
- Repeat as required.
It is important to note that you can add multiple placeholders either to one text box or across multiple text boxes as needed.
If you were to build the publication now, your placeholders would not be included in the output; this is because there is nothing to replace the placeholders with at this stage. Any static text in your text boxes will be included.
Step 3: Configure slicer to placeholder interactions
When you've added your placeholders, you need to use the Interaction Manager (opened from the Publish ribbon) to indicate which slicers should affect which placeholders:
The preceding selection (blue arrow above) indicates that the Country slicer should affect both Placeholder1 and Placeholder2. This means that, when you build this publication, you will be required to select a value from the Country slicer, and that value (or a value derived from it) will be used to replace both the placeholders in the output document.
- You can connect one slicer to multiple Placeholders, Visuals, and so on. Note that any Formula that you define when configuring the placeholder (next step) is defined per placeholder and not per slicer, meaning that the placeholder associated with your Country slicer (say) can be replaced with different values in the output.
- You cannot connect one placeholder to multiple slicers. This is because the placeholder is replaced in full.
Tip: You can create a slicer by clicking the Add New Slicer button from the top-right. This option opens the Advanced Slicer wizard. For more information, see New "Advanced" Slicer in Publish Pro
Step 4: Configure the placeholder (optional)
By default, the placeholder is named PlaceHolderX and is replaced with the value selected from the slicer at build time. If you would like to format the replacement value (make it Italic or Bold), or return a "manipulated" value (return a three character code instead of the Country name, or return some information about the selected country from the internet, for example), then you need to open the Dynamic Formula editor and update the formula there.
To open the Dynamic Formula editor, click the placeholder in its text box on the canvas. The editor opens at the bottom of the page:
Note: The default Formula, that causes the value selected from the slicer to replace this placeholder in the output publication, is value() (purple highlight above).
Details
Name
The Name field (green arrow above) changes the name of the placeholder here, in the Interaction Manager, and on the canvas. It is recommended that you always assign your placeholder a meaningful name to ensure it is easily identifiable.
Test Input
Type a test value into the Test Input field to use when validating your Formula. This should be a value that could realistically be selected from the slicer at build time. Click Validate to run the validation with this text at any time (see below).
Formula
By default, the Formula panel contains the value() string (purple highlight above). You can use the PQL Functions to build expressions that build a replacement value to add to the output document.
In the following example, we have added the Formula: LLM("Describe the best cuisine from " + value() + " include examples as bullets"):
This uses the LLM PQL function to find out what the best cuisine from the selected country is using your underlying LLM. When you build your output document, your placeholder is replaced with a block of text about cuisine in the selected country.
Note: The LLM function can be used to add additional information and background to your publication; it cannot tell you about your data set. You can only make use of this functionality if your administrator has selected the Enable Generative AI checkbox in the AI Settings page of the Admin Console. If your administrator does not select this option, the function is not available for use.
Functions
You can use the PQL functions in the Functions panel to create a PQL expression that adds markup to your value or that manipulates the result before it is used:
- The PQL libraries that are available in this panel are Common and Dynamic.
- You can search the functions by name using the Search field at the top of the Functions panel.
- You can hover your cursor over the item in the Functions tree to show a description of the available function, including its syntax.
- You can also double-click the functions in the tree to copy them into the Formula window. If you select content in the Formula panel and then double-click a function, anything that is selected is inserted within the parentheses.
Note: The Pyramid Query Language (PQL), pronounced "Prequel," is a language built into Pyramid's PYRANA engine to allow users to construct queries that can run against the many SQL data stacks that Pyramid can query natively. PQL includes a vast array of operations and functions that allow users to query data and build analytical logic.
- Click here for more Formula Examples
Validate
Test that the formula behaves as expected by entering a valid value into the Test Input field (blue arrow above) and clicking Validate (orange arrow above). The green strip indicates that the expression was validated successfully and the text shown in the strip is the returned output (hover to see more where the response is truncated):
Tip: You may need to resize the text box to fit the content returned by the expression. Always check the amount of text returned from some examples and resize your text box accordingly.
Apply
Click Apply to save your placeholder formula and close the Dynamic Place Holder panel.
Step 5: Build your publication
It is important to validate that your placeholders are having the effect you expect in the output publication. You might, therefore, want to run a scheduled build that selects all possible values from your slicer and produces a document for each that you can check. For example, you might want to schedule a build of your publication where the selection option is set to select All Items in the Country slicer:
- Click here for more information about scheduling builds
Formula Examples
The following examples show how the Dynamic and Common functions can be used to perform some logical actions. It's important to note that, for placeholders, the value() represents the value selected from the slicer at build time.
Change the Country Name into a Country Code
Use the functions from the Common library to replace your selected country name with a three-character country code:
- Replace the value "United States" from the slicer with "USA."
- Replace any other value from the slicer with a three-character, uppercase substring from the slicer.
Use the If() statement to as follows:
If(value() = "United States", "USA", ToUpper(SubString(value(), 0, 3)))
For more information about the functions, see If, ToUpper, and SubString.
Markup your Value
Use the functions in the Dynamic library to apply Markup to your value; for example, to make the name of the selected country Bold or Italic:
Bold(value())
Italics(value())
For more information about the functions, see Bold and Italics.
Related information
Using the LLM PQL Function
If you have Generative AI enabled, you can use the LLM function to generate replacement content for your placeholders, as shown in the main example above.
Pyramid's Generative AI integration enables you to use AI to generate scripts and images, dynamic text and infographics, calculations and lists, schedules, colors, and more. It allows you to generate a range of content, including complex code, simply by providing a text prompt.
Tip: You can use the LLM PQL function (from the Common PQL functions) to generate dynamic text, adding the results to custom tooltips, text fields, or into your PQL formulas. While this function cannot tell you about your data set, it can add additional information and background to your presentation or publication.
Warning: When using LLMs, your assets are generated using public domain algorithms. This can produce erroneous and inconsistent or random results. Use at your own risk.